#####################################################################
# Product:      KnowledgeEngine (Plone Edition)
#
# File:         KERLExtensions.py
#
# Copyright:    Copyright (c) 2004, Faulkner Technologies
#
# Author:       Brian Oliver
#
# Description:  This file defines the KERLExtensions class/interface,
#               that must be implemented by components that
#               extend/provide additional rule expressions for KERL.
#
# See Also:     KERLProcessor, Component
#####################################################################

#####################################################################
## KnowledgeEngine Library Imports
from Common import *

#####################################################################
## Zope Library Imports
# (none)

 
#####################################################################
## Python Library Imports
# (none)

#####################################################################
## KERLExtensions Class Definition
class KERLExtensions:
    """
        An interface implemented by Components extending the
        Knowledge Engine Rule Language (KERL).

        NOTE: In essence the methods defined by this class should
        be 'class methods'.  That is, they essentially do not require
        instance attributes to execute.  However, defining them as
        instance methods simply permits optimized evaluation of
        KERL expressions and the opportunity to evaluate KERLs
        in the context of specific component instances.
    """

    #---------------------------------------------------------------#

    def compileKERLtoJavaScript(self, expression):
        """
            Returns a Python string that represents a JavaScript
            expression, which may be used to evaluate the status
            of the component class specific KERL expression.

            NOTE: this method is primarily used to produce
            JavaScript expressions that form the basis of the
            client-side showif technology.
            
            RETURN TYPE: String         
        """
        
        return ""

    #---------------------------------------------------------------#

    def compileKERLtoEnglish(self, expression):
        """
            Returns a string representing an 'English' version
            of the component class specific KERL expression.

            NOTE: this method is primarily used to produce
            English descriptions of KERL expressions that may be 
            used to describe things like AssessmentFilters
            
            RETURN TYPE: String         
        """
        
        return ""

    #---------------------------------------------------------------#

    def evaluate(self, expression, assessment):
        """
            Evalutes the component class specific KERL expression
            using the provided assessment.

            NOTE: this method is primarily used to produce
            JavaScript expressions that form the basis of the
            client-side showif technology.

            RETURN TYPE: Boolean         
        """
        
        return true
    
    #---------------------------------------------------------------#

    def getDependencies(self, expression):
        """
            Returns a list of components that are required to
            evaluate the component class specific KERL expression.

            NOTE: Includes the specific component itself.

            RETURN TYPE: {Component} indexed by Component.getIdentity()
       """

        return {self.getIdentity():self}
    
    #---------------------------------------------------------------#

    def updateKERLIdentities(self, expression, identityMappings):
        """
            Returns the expression with the appropriate old identities
            (as identified by the identityMappings) replaced with 
            new identities.
        """
        
        #by default, don't do anything   
        return expression

    #---------------------------------------------------------------#

#####################################################################
## Class Initialisation
# (none)
